package com.kexio.sms.service;

import com.kexio.common.dto.Result;
import com.kexio.sms.entity.VerificationCode;

/**
 * 短信验证码服务接口
 * 
 * @author Kexio Team
 * @since 1.0.0
 */
public interface SmsVerificationService {
    
    /**
     * 发送验证码
     * 
     * @param phone 手机号码
     * @param type 验证码类型 (login, register, reset_password, modify_phone)
     * @param businessType 业务类型
     * @return 发送结果
     */
    Result<String> sendVerificationCode(String phone, String type, String businessType);
    
    /**
     * 发送验证码 (自定义长度和有效期)
     * 
     * @param phone 手机号码
     * @param type 验证码类型
     * @param businessType 业务类型
     * @param length 验证码长度
     * @param expireMinutes 有效期 (分钟)
     * @return 发送结果
     */
    Result<String> sendVerificationCode(String phone, String type, String businessType, int length, int expireMinutes);
    
    /**
     * 验证验证码
     * 
     * @param phone 手机号码
     * @param code 验证码
     * @param type 验证码类型
     * @return 验证结果
     */
    Result<Boolean> verifyCode(String phone, String code, String type);
    
    /**
     * 验证验证码 (验证后自动失效)
     * 
     * @param phone 手机号码
     * @param code 验证码
     * @param type 验证码类型
     * @param consumeOnSuccess 验证成功后是否消费 (标记为已使用)
     * @return 验证结果
     */
    Result<Boolean> verifyCode(String phone, String code, String type, boolean consumeOnSuccess);
    
    /**
     * 获取验证码信息 (不包含验证码内容)
     * 
     * @param phone 手机号码
     * @param type 验证码类型
     * @return 验证码信息
     */
    VerificationCode getVerificationInfo(String phone, String type);
    
    /**
     * 检查是否可以发送验证码 (频率限制)
     * 
     * @param phone 手机号码
     * @param type 验证码类型
     * @return 是否可以发送
     */
    Result<Boolean> canSendCode(String phone, String type);
    
    /**
     * 清除验证码
     * 
     * @param phone 手机号码
     * @param type 验证码类型
     * @return 清除结果
     */
    Result<Boolean> clearCode(String phone, String type);
    
    /**
     * 获取剩余有效时间 (秒)
     * 
     * @param phone 手机号码
     * @param type 验证码类型
     * @return 剩余时间
     */
    long getRemainingTime(String phone, String type);
    
    /**
     * 生成验证码 (不发送)
     * 
     * @param length 验证码长度
     * @return 验证码
     */
    String generateCode(int length);
    
    /**
     * 批量清理过期验证码
     * 
     * @return 清理数量
     */
    int cleanExpiredCodes();
}
